Using the HTTP Post Method to Obtain Data to Download

The SamplePost application calls URLDownload to download information from the InterNIC's whois database. The file SamplePost.h, shown in Listing 2-1 , defines the URL (kSampleURL ) from which data is to be downloaded and the structure urlDownInfo , which contains all of the information needed to download data from the sample URL.

The SamplePost.h file also includes a declaration of the routine DoSamplePost , which does the actual download, and a system event callback routine, MyURLCallbackProc , which is a place holder for code that handles system events that occur during the download.

The SamplePost application is multi-threaded, so it calls MaxApplZone and MoreMasters in its main routine, as shown in Listing 2-2 .

In Listing 2-4 , the DoSamplePost routine defines a URLDownloadInfo structure named myRef that is uses to store information for calling URLDownload. The DoSamplePost routine calls NewHandle to allocate the memory in which the downloaded information will be stored. Then DoSamplePost creates a URL reference and stores it in myRef.urlRef , which will be used as a parameter when DoSamplePost calls URLDownload .

Next, DoSamplePost completes the preparation of the URL reference by calling URLSetProperty to set the value of the URL reference's HTTP Request Method property to POST (a 4-byte string) and the value of the URL reference's HTTP Request Body property to whois_nic=apple.com (a 19-byte string), as shown in Listing 2-5 .

Note

When you set the HTTP Request Body property, the URL Access Manager automatically adds the length of the HTTP Request Header to the request, so you do not need to set the HTTP Request Header property explicitly.

Listing 2-6 , DoSamplePost uses the remaining fields of the myRef structure to store values that will be used as parameters for calling URLDownload .

Listing 2-6 Setting the URLDownload parameters



 
    myRef.destination = nil;

    myRef.destinationHandle = downloadHandle;

    myRef.openFlags = kURLDisplayProgressFlag;

    myRef.eventProc = &MyURLCallbackProc;

    myRef.userContext = "1";

    myRef.errorCode = 0;

Specifically, DoSamplePost does the following in Listing 2-6 :

Sets myRef.destination to nil . When nil is provided as the destination parameter to the URLDownload function, the calling application indicates that the downloaded data is not going to be written to a file on disk.
Sets myRef.destinationHandle to the value of downloadHandle , which is the location in memory at which the downloaded data is to be stored.
Sets myRef.OpenFlags to kURLDisplayProgressFlag . When the value of the openFlags parameter to URLDownload is kURLDisplayProgressFlag , the URLDownload function displays a progress indicator during the download process.
Sets myRef.eventProc to the address of the SamplePost application's system event callback routine. When DoSamplePost calls URLDownload , it will specify myRef.eventProc as the eventProc parameter. If a system event occurs while the progress indicator is displayed, the URL Access Manager will call the routine specified by the eventProc parameter and will pass to it the value of the userContext parameter, which is described next.
Sets myRef.userContext to 1. When DoSamplePost calls URLDownload , it will specify myRef.userContext as the userContext parameter. Your application can use the user context to associate any particular call of URLDownload with any particular call of the system event callback routine.

With the URL reference created, its properties set, and the URLDownload parameters prepared, the DoSamplePost routine is ready to call URLDownload , as shown in Listing 2-7 .

Listing 2-7 Calling the URLDownload function



 
    err = URLDownload( myRef.urlRef,

        myRef.destination,

        myRef.destinationHandle,

        myRef.openFlags,

        myRef.eventProc,

        myRef.userContext);

    myRef.errorCode = err;



    if (  myRef.errorCode != noErr) {

        // Call error handling routine.

    }

    else {

    // Successful download. Get the size of the downloaded data.

    err = URLGetProperty(myRef.urlRef,

        kURLResourceSize, &downloadSize, 4);

    if ( err != noErr) {

        // Call error handling routine.

    }

In Listing 2-7 , if the download is successful, the DoSamplePost routine calls URLGetProperty to obtain the size of the downloaded data using the downloadSize parameter, which is 4 bytes long.

In Listing 2-8, DoSamplePost calls SetHandleSize to set the size of downloadHandle to downloadSize + 1 and sets the value of the last byte of downloaded data to NIL . Now that data can be displayed by calling printf . The DoDownload routine concludes by disposing of the URL reference.

Listing 2-8 Displaying the downloaded data



 


downloadSize = GetHandleSize(downloadHandle);

SetHandleSize(downloadHandle, (downloadSize+1));

(*myRef.destinationHandle)[downloadSize] = nil;



printf( "<·>==================== Downloaded Data ==================\n" );

printf( "%s", *myRef.destinationHandle );

DisposeHandle(downloadHandle);

URLDisposeReference(myref.urlRef);

    }

}

Listing 2-9 shows the SamplePost application's system event callback routine.

Listing 2-9 The SamplePost application's system event callback routine



 
pascal OSStatus MyURLCallbackProc( void *userContext, EventRecord *event )

{

    printf( "<·>System callback thread fired! Thread: %u\n", userContext );

    return 0;

}

The system event callback routine receives in userContext the value of the userContext parameter that was passed when the application called URLDownload .

Your application's system event callback routine should process the event record passed by the event parameter and return 0.